:::info 提醒
为了让用户更方便地使用这些组件，Rspress 内部对于 `rspress/theme` 这个包做了 alias 处理，所以你可以直接使用 `@theme` 来引入这些组件。
:::

## Badge

Badge 组件用于展示状态的标记。使用方法如下：

```tsx title="index.mdx"
import { Badge } from '@theme';

function App() {
  // 使用 text 属性
  return <Badge text="info" type="info" />;

  // 使用自定义子元素
  return (
    <Badge>
      <img
        style={{ height: '18px' }}
        src="https://assets.rspack.rs/rspress/rspress-logo.svg"
      />
      <span>Rspress</span>
    </Badge>
  );
}
```

效果如下：

import { Badge } from '@theme';

<Badge text="tip" type="tip" />
<Badge text="info" type="info" />
<Badge text="warning" type="warning" />
<Badge text="danger" type="danger" />
<Badge text="outlined" outline />

import SearchSvg from '@theme-assets/github';

自定义子元素：

<Badge type="tip">
  <img
    style={{ height: '18px' }}
    src="https://assets.rspack.rs/rspress/rspress-logo.svg"
  />
  <span>Rspress</span>
</Badge>

<Badge type="info">
  <SearchSvg width="16" />
  <span>Github</span>
</Badge>

内联文本 <Badge text="Tip" />

##### H5 <Badge text="Info" type="info" />

#### H4 <Badge text="Warning" type="warning" />

### H3 <Badge text="Danger" type="danger" />

其中包含的 props 类型如下：

```ts
interface BadgeProps {
  /**
   * 在徽章内显示的内容。可以是字符串或 React 节点。
   */
  children?: React.ReactNode;
  /**
   * 徽章的类型，决定其颜色和样式。
   * @default 'tip'
   */
  type?: 'tip' | 'info' | 'warning' | 'danger';
  /**
   * 在徽章内显示的文本内容（为了向后兼容）。
   */
  text?: string;
  /**
   * 是否以轮廓样式显示徽章。
   * @default false
   */
  outline?: boolean;
}
```

## Head

一般用于在文档中设置自定义 head 内容（基于 [unhead](https://www.npmjs.com/package/unhead)）。使用方法如下：

```tsx title="index.tsx"
// 以下为一个自定义组件，你可以将其引入到文档中
import { Head } from '@rspress/core/runtime';

function App() {
  return (
    <Head>
      <meta property="og:description" content="Out-of-box Rspack build tools" />
    </Head>
  );
}
```

## HomeFeature

Home 页面 Feature 组件，查看[本站的效果](/zh/)

```tsx
import { HomeFeature } from '@rspress/core/theme';

interface Feature {
  title: string;
  details: string;
  icon: string;
  // 卡片栅格的长度，目前仅支持[3, 4, 6]
  span?: number;
  // feature 卡片跳转链接，选填
  link?: string;
}

export type Features = Feature[];
```

## HomeHero

Home 页面 Hero 组件

```tsx
import { HomeHero } from '@rspress/core/theme';

interface Hero {
  name: string;
  text: string;
  tagline: string;
  image?: {
    src: string | { dark: string; light: string };
    alt: string;
  };
  actions: {
    text: string;
    link: string;
    theme: 'brand' | 'alt';
  }[];
}
```

## LastUpdated

LastUpdated 组件用来显示文章的最后更新时间。使用方法如下：

```tsx title="index.mdx"
import { LastUpdated } from '@theme';

function App() {
  return <LastUpdated />;
}
```

:::tip

如果没有在默认主题中配置 `lastUpdated: true` 的话需要安装和注册 `@rspress/plugin-last-updated` 插件。

:::

## NoSSR

用于在服务端渲染时不渲染某些组件。使用方法如下：

```tsx
import { NoSSR } from '@rspress/core/runtime';

const Component = () => {
  return (
    <NoSSR>
      <div>这里的内容只会在客户端渲染</div>
    </NoSSR>
  );
};
```

## Overview

预览组件，查看[本站的效果](/zh/api/)

```tsx
import { Overview } from '@rspress/core/theme';

interface GroupItem {
  text?: string;
  link?: string;
  headers?: Header[];
}

interface Group {
  name: string;
  items: GroupItem[];
}

interface OverviewProps {
  // 预览部分上方的内容
  content?: React.ReactNode;
  // 预览数据
  groups?: Group[];
  // 默认标题
  defaultGroupTitle?: string;
  // 在预览页中展示的标题级别
  overviewHeaders?: number[];
}
```

## PackageManagerTabs

PackageManagerTabs 组件用于在文档中展示不同包管理器的命令。使用方法如下：

```tsx title="index.mdx"
import { PackageManagerTabs } from '@theme';

function App() {
  return <PackageManagerTabs command="install -D @rspress/core" />;
}
```

效果如下：

import { PackageManagerTabs } from '@theme';

<PackageManagerTabs command="install -D @rspress/core" />

其中包含的 props 类型如下：

```ts
type PackageManagerTabProps = (
  | {
      command: string;
      /**
       * 如果为 true，使用本地包执行（npx、yarn、pnpm、bun、deno run）。
       * 用于 node_modules 中安装的本地包。
       */
      exec?: boolean;
      /**
       * 如果为 true，使用远程包执行（npx、yarn dlx、pnpm dlx、bunx、deno run）。
       * 用于直接从源下载并执行包而无需本地安装。
       * 优先于 exec 属性。
       */
      dlx?: boolean;
    }
  | {
      command: {
        // 用于为不同的包管理器设置命令
        npm?: string;
        yarn?: string;
        pnpm?: string;
        bun?: string;
        deno?: string;
      };
      exec?: never;
      dlx?: never;
    }
) &
  // 用于设置额外的 tabs
  {
    additionalTabs?: {
      // 用于设置额外的包管理器
      tool: string;
      // 用于设置额外包管理器的图标
      icon?: ReactNode;
    }[];
  };
```

当 `command` 设置为字符串时，会默认展示 npm、yarn、pnpm、bun、deno 五个 tab，并且组件内部为自动在 command 前面添加对应的包管理器命令。如果你需要展示额外的 tab，可以通过 `additionalTabs` 来实现。

你也可以使用对象形式为每个包管理器设置不同的命令：

```tsx title="index.mdx"
import { PackageManagerTabs } from '@theme';

function App() {
  return (
    <PackageManagerTabs
      command={{
        npm: 'npm create rspress@latest',
        yarn: 'yarn create rspress',
        pnpm: 'pnpm create rspress@latest',
        bun: 'bun create rspress@latest',
        deno: 'deno init --npm rspress@latest',
      }}
    />
  );
}
```

:::tip

- 在 install 命令中，对 yarn、pnpm、bun 和 deno 做了特殊处理，如果你的命令是`install some-packages`，在 yarn、pnpm、bun 和 deno 的 tab 中会自动将 install 替换为 add。
- 在 deno 的 tab 中会默认为没有指定来源的包加上 `npm:` 前缀。

:::

## PrevNextPage

PrevNextPage 组件用来渲染上一页和下一页的链接。使用方法如下：

```tsx title="index.mdx"
import { PrevNextPage } from '@theme';

function App() {
  return <PrevNextPage type="prev" text="上一页" href="https://rspress.rs/" />;
}
```

其中包含的 props 类型如下：

```ts
interface PrevNextPageProps {
  // 通过 type 来设置该链接是上一页还是下一页
  type: 'prev' | 'next';
  // 用于设置上一页或下一页的文本
  text: string;
  // 用于设置上一页或下一页的链接
  href: string;
}
```

## SourceCode

SourceCode 组件用来跳转到源代码。使用方法如下：

```tsx title="index.mdx"
import { SourceCode } from '@theme';

function App() {
  return (
    <SourceCode href="https://github.com/web-infra-dev/rspress/blob/main/packages/theme-default/src/components/SourceCode/index.tsx" />
  );
}
```

效果如下：

import { SourceCode } from '@theme';

<SourceCode href="https://github.com/web-infra-dev/rspress/blob/main/packages/theme-default/src/components/SourceCode/index.tsx" />

其中包含的 props 类型如下：

```ts
interface SourceCodeProps {
  // 用于设置源代码的链接
  href: string;
  // 用于设置源平台
  platform?: 'github' | 'gitlab';
}
```

## Steps

Steps 组件用于将编号列表转换为步骤的可视化表示形式。使用方法如下：

```tsx title="index.mdx"
import { Steps } from '@theme';

function App() {
  return (
    <Steps>
      ### 第 1 步

      步骤 1 的正文

      ### 第 2 步

      > 步骤 2 的正文
    </Steps>
  );
}
```

效果如下:

import { Steps } from '@theme';

<Steps>
  ### 第 1 步

步骤 1 的正文

### 第 2 步

> 步骤 2 的正文

</Steps>

## Tab/Tabs

你可以在文档中使用 `Tab` 和 `Tabs` 组件来实现标签页切换的效果。比如：

```mdx title="index.mdx"
import { Tab, Tabs } from '@rspress/core/theme';

<Tabs>
  <Tab label="Tab 1">Tab 1 content</Tab>
  <Tab label="Tab 2">Tab 2 content</Tab>
</Tabs>
```

import { Tab, Tabs } from '@theme';

<Tabs>
  <Tab label="Tab 1">Tab 1 content</Tab>
  <Tab label="Tab 2">Tab 2 content</Tab>
</Tabs>

### 代码块切换

使用 `Tabs` 组件来切换多个代码块。

````mdx title="index.mdx"
import { Tab, Tabs } from '@rspress/core/theme';

<Tabs>
  <Tab label="Tab 1">

```tsx title="src/index.mjs"
import foo from 'foo';
import bar from 'bar';
```

  </Tab>
  <Tab label="Tab 2">

```tsx title="src/index.cjs"
const foo = require('foo');
const bar = require('bar');
```

  </Tab>
</Tabs>
````

<Tabs>
  <Tab label="Tab 1" value="1">

```tsx title="src/index.mjs"
import foo from 'foo';
import bar from 'bar';
```

  </Tab>
  <Tab label="Tab 2" value="2">

```tsx title="src/index.cjs"
const foo = require('foo');
const bar = require('bar');
```

  </Tab>
</Tabs>

### Props

Tabs 组件的 props 类型如下:

```ts
interface TabsProps {
  children: React.ReactNode;
  defaultValue?: string;
  groupId?: string;
  tabPosition?: 'left' | 'center';
}
```

- `defaultValue` 用于设置默认选中的 tab 项，这个值会和 Tab 组件的 value 字段做比较，如果相等则选中该 tab。
- `groupId` 用于设置 tab 项的分组，当你需要多个 Tabs 组件进行联动的时候，可以通过 groupId 来实现。groupId 相同的 Tabs 组件会进行联动。
- `tabPosition` 用于设置 tab 列表的排列位置，目前支持 `left` 和 `center` 两个值，分别表示靠左和居中，默认为 `left`。

Tab 组件的 props 类型如下:

```ts
interface TabProps {
  label: string;
  // 用于标识当前 tab，如果不传则默认使用 label
  value?: string;
  children: React.ReactNode;
}
```

其中的 `value` 字段用于标识当前 tab，如果不传则默认使用 label。

## CodeBlockRuntime

运行时渲染代码块

```tsx title="index.mdx"
import { CodeBlockRuntime } from '@theme';

function App() {
  return (
    <CodeBlockRuntime
      lang="js"
      title="index.js"
      code={`console.log('Hello World!')`}
      shikiOptions={{
        {/* shikiOptions */}
      }}
    />
  );
}
```

import { CodeBlockRuntime } from '@theme';

<CodeBlockRuntime
  lang="js"
  title="index.js"
  code={`console.log('Hello World!')`}
/>
